<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow: flow Namespace Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#namespaces">Namespaces</a> &#124;
<a href="#nested-classes">Classes</a> &#124;
<a href="#typedef-members">Typedefs</a> &#124;
<a href="#enum-members">Enumerations</a> &#124;
<a href="#var-members">Variables</a>  </div>
  <div class="headertitle"><div class="title">flow Namespace Reference</div></div>
</div><!--header-->
<div class="contents">

<p>Catch-all namespace for the Flow project: A collection of various production-quality modules written in modern C++17, originally by ygoldfel.  
<a href="namespaceflow.html#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="namespaces" name="namespaces"></a>
Namespaces</h2></td></tr>
<tr class="memitem:namespaceflow_1_1async"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow_1_1async.html">async</a></td></tr>
<tr class="memdesc:namespaceflow_1_1async"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow module containing tools enabling multi-threaded event loops operating under the asynchronous-task proactor pattern, by providing a streamlined API around boost.asio event loops with added advanced task- and thread-scheduling features. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceflow_1_1cfg"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow_1_1cfg.html">cfg</a></td></tr>
<tr class="memdesc:namespaceflow_1_1cfg"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow module that facilitates configuring modules, such as applications and APIs, via statically and/or dynamically parsed sets of name/value pairs from config sources like files and command lines. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceflow_1_1error"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow_1_1error.html">error</a></td></tr>
<tr class="memdesc:namespaceflow_1_1error"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow module that facilitates working with error codes and exceptions; essentially comprised of niceties on top <a class="el" href="namespaceboost_1_1system.html" title="We may add some ADL-based overloads into this namespace outside flow.">boost.system</a>'s error facility. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceflow_1_1log"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow_1_1log.html">log</a></td></tr>
<tr class="memdesc:namespaceflow_1_1log"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow module providing logging functionality. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceflow_1_1net__flow"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow_1_1net__flow.html">net_flow</a></td></tr>
<tr class="memdesc:namespaceflow_1_1net__flow"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow module containing the API and implementation of the <em>Flow network protocol</em>, a TCP-inspired stream protocol that uses UDP as underlying transport. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceflow_1_1perf"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow_1_1perf.html">perf</a></td></tr>
<tr class="memdesc:namespaceflow_1_1perf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow module containing tools for profiling and optimization. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:namespaceflow_1_1util"><td class="memItemLeft" align="right" valign="top">namespace &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow_1_1util.html">util</a></td></tr>
<tr class="memdesc:namespaceflow_1_1util"><td class="mdescLeft">&#160;</td><td class="mdescRight">Flow module containing miscellaneous general-use facilities that don't fit into any other Flow module. <br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="nested-classes" name="nested-classes"></a>
Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classflow_1_1Function.html">Function</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classflow_1_1Function_3_01Result_07Args_8_8_8_08_4.html">Function&lt; Result(Args...)&gt;</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Intended as the polymorphic function wrapper of choice for Flow, internally and externally; to be used instead of <code>std::function</code> or <code>boost::function</code>.  <a href="classflow_1_1Function_3_01Result_07Args_8_8_8_08_4.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="typedef-members" name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:ae02da22c4a101eaab447511c905e4f32"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow.html#ae02da22c4a101eaab447511c905e4f32">uint8_t</a> = unsigned char</td></tr>
<tr class="memdesc:ae02da22c4a101eaab447511c905e4f32"><td class="mdescLeft">&#160;</td><td class="mdescRight">Byte. Best way to represent a byte of binary data. This is 8 bits on all modern systems.  <a href="namespaceflow.html#ae02da22c4a101eaab447511c905e4f32">More...</a><br /></td></tr>
<tr class="separator:ae02da22c4a101eaab447511c905e4f32"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a96b8a241b21c907e96cb91f4bf868446"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow.html#a96b8a241b21c907e96cb91f4bf868446">int8_t</a> = signed char</td></tr>
<tr class="memdesc:a96b8a241b21c907e96cb91f4bf868446"><td class="mdescLeft">&#160;</td><td class="mdescRight">Signed byte. Prefer to use <code>uint8_t</code> when representing binary data. This is 8 bits on all modern systems.  <a href="namespaceflow.html#a96b8a241b21c907e96cb91f4bf868446">More...</a><br /></td></tr>
<tr class="separator:a96b8a241b21c907e96cb91f4bf868446"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8f2e48761f9ca3ffcaa29872078bbf00"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow.html#a8f2e48761f9ca3ffcaa29872078bbf00">Fine_clock</a> = boost::chrono::high_resolution_clock</td></tr>
<tr class="memdesc:a8f2e48761f9ca3ffcaa29872078bbf00"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clock used for delicate time measurements, such that the <code>now()</code> method gets the current time relative to some unknown but constant epoch (reference point).  <a href="namespaceflow.html#a8f2e48761f9ca3ffcaa29872078bbf00">More...</a><br /></td></tr>
<tr class="separator:a8f2e48761f9ca3ffcaa29872078bbf00"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a9d9cc2eeb10d398cff5591d446b763b8"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow.html#a9d9cc2eeb10d398cff5591d446b763b8">Fine_time_pt</a> = Fine_clock::time_point</td></tr>
<tr class="memdesc:a9d9cc2eeb10d398cff5591d446b763b8"><td class="mdescLeft">&#160;</td><td class="mdescRight">A high-res time point as returned by <code>Fine_clock::now()</code> and suitable for precise time math in general.  <a href="namespaceflow.html#a9d9cc2eeb10d398cff5591d446b763b8">More...</a><br /></td></tr>
<tr class="separator:a9d9cc2eeb10d398cff5591d446b763b8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a48799f1263cdeedec125be51a3db2b79"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow.html#a48799f1263cdeedec125be51a3db2b79">Fine_duration</a> = Fine_clock::duration</td></tr>
<tr class="memdesc:a48799f1263cdeedec125be51a3db2b79"><td class="mdescLeft">&#160;</td><td class="mdescRight">A high-res time duration as computed from two <code>Fine_time_pt</code>s.  <a href="namespaceflow.html#a48799f1263cdeedec125be51a3db2b79">More...</a><br /></td></tr>
<tr class="separator:a48799f1263cdeedec125be51a3db2b79"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a29eaaa9d0fac4ce87d8b969222dbed09"><td class="memItemLeft" align="right" valign="top">using&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09">Error_code</a> = boost::system::error_code</td></tr>
<tr class="memdesc:a29eaaa9d0fac4ce87d8b969222dbed09"><td class="mdescLeft">&#160;</td><td class="mdescRight">Short-hand for a <a class="el" href="namespaceboost_1_1system.html" title="We may add some ADL-based overloads into this namespace outside flow.">boost.system</a> error code (which basically encapsulates an integer/<code>enum</code> error code and a pointer through which to obtain a statically stored message string); this is how Flow modules report errors to the user; and we humbly recommended all C++ code use the same techniques.  <a href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09">More...</a><br /></td></tr>
<tr class="separator:a29eaaa9d0fac4ce87d8b969222dbed09"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="enum-members" name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:a3938730ab4b89daf13d027a5f620e7ce"><td class="memItemLeft" align="right" valign="top">enum class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce">Flow_log_component</a> { <a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7cea6fba12db09e5bebfaa04f6372c41c2cf">S_END_SENTINEL</a>
 }</td></tr>
<tr class="memdesc:a3938730ab4b89daf13d027a5f620e7ce"><td class="mdescLeft">&#160;</td><td class="mdescRight">The <a class="el" href="classflow_1_1log_1_1Component.html" title="A light-weight class, each object storing a component payload encoding an enum value from enum type o...">flow::log::Component</a> payload enumeration comprising various log components used by Flow's own internal logging.  <a href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce">More...</a><br /></td></tr>
<tr class="separator:a3938730ab4b89daf13d027a5f620e7ce"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="var-members" name="var-members"></a>
Variables</h2></td></tr>
<tr class="memitem:abef6a1249edc3dd6c7f650235a84bfe4"><td class="memItemLeft" align="right" valign="top">const boost::unordered_multimap&lt; <a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce">Flow_log_component</a>, std::string &gt;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespaceflow.html#abef6a1249edc3dd6c7f650235a84bfe4">S_FLOW_LOG_COMPONENT_NAME_MAP</a></td></tr>
<tr class="memdesc:abef6a1249edc3dd6c7f650235a84bfe4"><td class="mdescLeft">&#160;</td><td class="mdescRight">The map generated by <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> macro magic that maps each enumerated value in <a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce" title="The flow::log::Component payload enumeration comprising various log components used by Flow&#39;s own int...">flow::Flow_log_component</a> to its string representation as used in log output and verbosity config.  <a href="namespaceflow.html#abef6a1249edc3dd6c7f650235a84bfe4">More...</a><br /></td></tr>
<tr class="separator:abef6a1249edc3dd6c7f650235a84bfe4"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p >Catch-all namespace for the Flow project: A collection of various production-quality modules written in modern C++17, originally by ygoldfel. </p>
<p >(The very first version was in Boost-y C++03, back around 2010. Later, ~2019, it moved to C++14 in style and substance; and in 2022 to C++17 &ndash; a relatively minor upgrade.) While the modules are orthogonal to each other in terms of functionality provided, they all share a common set of stylistic conventions and happen to use each other internally; hence they are distributed together as of this writing.</p>
<p >From the user's perspective, one should view this namespace as the "root," meaning it consists of two parts:</p><ul>
<li>Sub-namespaces (like <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a>, <a class="el" href="namespaceflow_1_1util.html" title="Flow module containing miscellaneous general-use facilities that don&#39;t fit into any other Flow module...">flow::util</a>, <a class="el" href="namespaceflow_1_1async.html" title="Flow module containing tools enabling multi-threaded event loops operating under the asynchronous-tas...">flow::async</a>, <a class="el" href="namespaceflow_1_1net__flow.html" title="Flow module containing the API and implementation of the Flow network protocol, a TCP-inspired stream...">flow::net_flow</a>), each of which represents a <em>Flow module</em> providing certain grouped functionality. Each module is self-contained from the point of view of the user, meaning: While the various modules may use each other internally (and hence cannot be easily distributed separately), from user's perspective each one can be directly <code>include</code>d/referenced without directly <code>include</code>ing/referring to the others. E.g., one can directly reference <code>namespace log</code> <em>and/or</em> <code>namespace util</code> <em>and/or</em> <code>namespace <a class="el" href="namespaceflow_1_1net__flow.html" title="Flow module containing the API and implementation of the Flow network protocol, a TCP-inspired stream...">net_flow</a></code> <em>and/or</em> .... Further documentation can be found in the doc headers for each individual sub-namespace.</li>
<li>Symbols directly in <code>flow</code>: The absolute most basic, commonly used symbols (such as <code>uint32_t</code> or <code>Error_code</code>). There should be only a handful of these, and they are likely to be small.<ul>
<li>In particular this includes <code>enum class Flow_log_component</code> which defines the set of possible <a class="el" href="classflow_1_1log_1_1Component.html" title="A light-weight class, each object storing a component payload encoding an enum value from enum type o...">flow::log::Component</a> values logged from within all modules of Flow (again, including <a class="el" href="namespaceflow_1_1util.html" title="Flow module containing miscellaneous general-use facilities that don&#39;t fit into any other Flow module...">flow::util</a>, <a class="el" href="namespaceflow_1_1async.html" title="Flow module containing tools enabling multi-threaded event loops operating under the asynchronous-tas...">flow::async</a>, <a class="el" href="namespaceflow_1_1net__flow.html" title="Flow module containing the API and implementation of the Flow network protocol, a TCP-inspired stream...">flow::net_flow</a>, etc.). See end of common.hpp.</li>
</ul>
</li>
</ul>
<p >Reiterating: Non-<code>namespace</code> symbols directly inside <code>namespace flow</code> are to be only extremely ubiquitous items such as the basic integer types and the log component <code>enum</code>. Anything beyond that should go into a sub-<code>namespace</code> of <code>flow</code>; if it is something miscellaneous then put it into <a class="el" href="namespaceflow_1_1util.html" title="Flow module containing miscellaneous general-use facilities that don&#39;t fit into any other Flow module...">flow::util</a>.</p>
<p >Here we summarize topics relevant to all of Flow. It is recommend one reads this before using any individual module, for topics like file organization and style conventions, topics arguably not of huge practical value right away. However, all the actual functionality is in the sub-modules, so once you're ready to actually do stuff, I reiterate: See the list of sub-namespaces of <code>flow</code> and start with the doc header of the one(s) of interest to you.</p>
<h2>Documentation / Doxygen </h2>
<p >All code in the project proper follows a high standard of documentation, almost solely via comments therein (as opposed to ancillary doc files/READMEs/etc.). Additionally, a subset of comments are Doxygen-targeted, meaning the comment starts with a special character sequence to cause the Doxygen utility to treat that comment as a doc header for a nearby symbol (class, method, etc.). (If you're not familiar with Doxygen: It's like Javadoc but better &ndash; although mostly compatible with Javadoc-targeted comments as well &ndash; not that we care about that.)</p>
<p >From the same source code (the entire Flow tree) 2 (two) web docs are generated by Doxygen utility &ndash; depending on which of the 2 Doxygen configuration files is chosen. You can determine which web docs you're reading currently (if indeed you are doing that, as opposed to reading raw code) via the wording of the title/header in every web page:</p><ul>
<li><em>Flow project: Full implementation reference</em>: This scans every header and translation unit file, including those in detail/ sub-directories at all levels; and all Doxygen-targeted comments (including this one) are fully scanned. Full browsable source code is included in the output also. As a result, it's basically an ultra-nice viewer of the entire source code (implementation included), with special emphasis on doc headers such as this one.</li>
<li><em>Flow project: Public API</em>: Only headers are scanned; and all detail/ sub-directories at all levels are ignored. Additionally, any text following the (optional) <code>"@internal"</code> Doxygen command within each given Doxygen comment is ignored. Browsable source code is omitted. As a result, a clean public API documentation is generated with no "fat."</li>
</ul>
<p >While an important (achieved) goal is to keep the documentation of the library (internal and external, as noted) self-contained &ndash; within the source code or auto-generated by taking that source code as input &ndash; nevertheless some satellite documentation is likely to exist; for example to cover such things as the logistical state of the project, its test harness, perhaps the license, etc. Look outside the root src/flow directory.</p>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000016">Todo:</a></b></dt><dd>As of this writing the <em>exact</em> nature of where the project will permanently reside (and who will maintain it vs. use it) is in flux. Therefore for now I have removed the section covering certain topics and replaced it with the to-do you're reading. This should be undone when things settle down (obviously ensuring the brought-back section is made accurate). The topics to cover: <code>"@author"</code> (including contact info); GitHub/other address indicating where to browse the project source; link(s) to the latest auto-generated web docs (if any); a section on the history of the project; and licensing info (if deemed needed) or pointer to it. (Reminder: Also update any similar sections of the historically significant <a class="el" href="classflow_1_1net__flow_1_1Node.html" title="An object of this class is a single Flow-protocol networking node, in the sense that: (1) it has a di...">net_flow::Node</a> doc header.)</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000017">Todo:</a></b></dt><dd>Since Flow gained its first users beyond the original author, some Flow-adjacent code has been written from which Flow can benefit, including a potential <code>io</code> module/namespace for general networking/local I/O. (Flow itself continued to be developed, but some features were added elsewhere for expediency; this is a reminder to factor them out into Flow for the benefit of all.) Some features to migrate here might be: boost.asio extensions to UDP receive APIs to obtain receipt time stamps and destination IP (<code>recvmsg()</code> with ancillary data extensions) and to receive multiple datagrams in one call (<code>recvmmsg()</code>); boost.asio-adjacent facility to add custom socket options similarly to how boost.asio does it internally; boost.asio support for (local) transmission of native socket handles and security data over stream sockets (<code>SCM_RIGHTS</code>, etc.).</dd></dl>
<h2>Using Flow modules </h2>
<p >This section discusses usability topics that apply to all Flow modules including hopefully any future ones but definitely all existing ones as of this writing.</p>
<h3>Error reporting</h3>
<p >Similarly to boost.asio, all public methods that may return errors can either do so via an error code or an exception encapsulating that same error code. If user passes in non-null pointer to a <a class="el" href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09" title="Short-hand for a boost.system error code (which basically encapsulates an integer/enum error code and...">flow::Error_code</a> variable, the latter is set to success (falsy) or a specific failure (truthy <code>enum</code> value). If user passes in null pointer, an exception <code>exc</code> is thrown only in case of error and will encapsulate that error code (accessible via <code>exc.code()</code>).</p>
<p >For details about error reporting, see doc headers for <a class="el" href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09" title="Short-hand for a boost.system error code (which basically encapsulates an integer/enum error code and...">flow::Error_code</a> (spoiler alert: a mere alias to <code>boost::system::error_code</code>) and <code>namespace</code> <a class="el" href="namespaceflow_1_1error.html" title="Flow module that facilitates working with error codes and exceptions; essentially comprised of niceti...">flow::error</a>.</p>
<h3>Logging</h3>
<p >The <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> namespace (see especially <a class="el" href="classflow_1_1log_1_1Logger.html" title="Interface that the user should implement, passing the implementing Logger into logging classes (Flow&#39;...">log::Logger</a> and the various <code>FLOW_LOG_...*()</code> macros in <a class="el" href="log_8hpp.html">log/log.hpp</a>) provides a logging facility &ndash; used by Flow modules' often-extensive logging, and equally available to the Flow user. Ultimately, you may tweak the log level and then observe the given Flow module's internal behavior to whatever level of detail you desire. Similarly, as the user, you may use this system for your own logging, even if you use no Flow module other than <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> itself. Either way, you can hook up <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> to log via your own log output device in arbitrary fashion (e.g., save the log messages in a database, if that's what you want).</p>
<p >For details about logging, see doc header for <code>namespace</code> <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a>.</p>
<h2>Implementation notes </h2>
<p >There is a high standard of consistency and style, as well as documentation, in Flow. Before making changes to the code, you must read <a class="el" href="doc-coding__style_8cpp.html" title="Doc file (meant for reading, not compiling) that formally defines the coding style for the rest of th...">doc-coding_style.cpp</a>.</p>
<h3>Source file tree organization</h3>
<p >See <a class="el" href="doc-coding__style_8cpp.html" title="Doc file (meant for reading, not compiling) that formally defines the coding style for the rest of th...">doc-coding_style.cpp</a> which covers this topic.</p>
<h3>Libraries used; Boost</h3>
<p >We use STL and several Boost libraries (notably boost.asio) extensively. See <a class="el" href="doc-coding__style_8cpp.html" title="Doc file (meant for reading, not compiling) that formally defines the coding style for the rest of th...">doc-coding_style.cpp</a> which covers this topic.</p>
<h3>Exceptions</h3>
<p >For reasons of speed (hearsay or reputational though they may be) we avoid exception-throwing boost.asio routines inside the modules' implementations, even though using them would make the code a bit simpler in many areas. Similarly, we avoid throwing our own exceptions only to catch them higher in the back-trace. In both cases, we typically use error codes/return values. These are not absolute/hard rules, as exceptions may be used where minuscule speed improvements are immaterial (like the initialization and shutdown of a long-lived object such as <a class="el" href="classflow_1_1net__flow_1_1Node.html" title="An object of this class is a single Flow-protocol networking node, in the sense that: (1) it has a di...">net_flow::Node</a>).</p>
<p >After a recent look at performance implications of exceptions, the following is the basic conclusion: Exceptions have no processor cycle cost, unless actually thrown, in which case the perf cost can be non-trivial. Since we consider internal performance of paramount importance, we generally avoid throwing exceptions &ndash; only to catch them internally &ndash; as noted in the preceding paragraph. Arguably such situations are rare anyway, so using an exception internally wouldn't actually slow anything down, but we haven't performed a code audit to verify that stipulation; and in the meantime the consistent avoidance of using internally caught exceptions has proved to be a very reasonable policy. (For some modules this may be arguably mostly moot: Consider <a class="el" href="namespaceflow_1_1net__flow.html" title="Flow module containing the API and implementation of the Flow network protocol, a TCP-inspired stream...">flow::net_flow</a> specifically: Since &ndash; internally &ndash; mostly boost.asio <code>async_*()</code> methods are used, and those by definition report errors as codes passed into async handler functions; whether to use an exception or not is an ill-formed question in all such situations.) We recommend this practice continue, until there's a specific reason to reconsider.</p>
<p >See <a class="el" href="doc-coding__style_8cpp.html" title="Doc file (meant for reading, not compiling) that formally defines the coding style for the rest of th...">doc-coding_style.cpp</a> for more discussion of error handling and exceptions.</p>
<h2>Code style guidelines </h2>
<h3>General coding style requirements</h3>
<p >The formal guidelines are in <a class="el" href="doc-coding__style_8cpp.html" title="Doc file (meant for reading, not compiling) that formally defines the coding style for the rest of th...">doc-coding_style.cpp</a>; read that file please.</p>
<h3>Documentation guidelines</h3>
<p >The standard for documentation of Flow modules is that someone reading the source code, and nothing else, would be able to understand that code (modulo having the intellectual sophistication/experience w/r/t the subject matter, of course). Simple but quite a task given how much code there is and the complexity. We also produce Doxygen output (2 web pages, as of this writing) by running the code through Doxygen.</p>
<dl class="section see"><dt>See also</dt><dd>More on the technicalities of how we run Doxygen, and the philosophy behind all of that, can be found in a <code>doc/</code> or similar directory outside src/flow. It's rare something pertinent to the source code is not IN the source code (i.e., right here somewhere), but the README explains why that rare choice is made (among many more practical/interesting things). This is worth reading if you'll be contributing to the code.</dd></dl>
<p>The actual guidelines are, as above, in <a class="el" href="doc-coding__style_8cpp.html" title="Doc file (meant for reading, not compiling) that formally defines the coding style for the rest of th...">doc-coding_style.cpp</a>; read that file please.</p>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000018">Todo:</a></b></dt><dd>Possibly document exceptions thrown explicitly via the Doxygen keyword meant for this purpose: <code>"@throws"</code>. Currently when we document explicitly throwing an exception, it is ALWAYS a <a class="el" href="classflow_1_1error_1_1Runtime__error.html" title="An std::runtime_error (which is an std::exception) that stores an Error_code.">flow::error::Runtime_error</a> encapsulating a <a class="el" href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09" title="Short-hand for a boost.system error code (which basically encapsulates an integer/enum error code and...">flow::Error_code</a> (which is an <code>int</code>-like error code). This is very explicitly documented, but technically Doxygen has a keyword which will generate a special little readout for the exception (similarly as for each parameter, etc.). We don't use that keyword. We probably should, though this isn't totally cut-and-dried. Consider that we already document the exception on the <code>err_code</code> parameter in every case; so no information would really be gained (only arguably nicer formatting). On the other hand, the code would be somewhat more verbose (and boiler-platey, since each already boiler-platey <code>err_code</code> comment snippet would essentially grow in size). Furthermore, if we document this explicit exception, one might say it behooves us to now document all the other possible sources of exceptions such as <code>std::bad_alloc</code> when running out of heap memory. Perhaps then we have to talk about constructor-throwing-exception behavior and other C++ technicalities to do with exceptions. Do we really want to enter that land? I think maybe not; consider just leaving it alone. Though, maybe I'm over-dramatizing the impact of adding a <code>"@throws"</code> section on our various <a class="el" href="classflow_1_1error_1_1Runtime__error.html" title="An std::runtime_error (which is an std::exception) that stores an Error_code.">flow::error::Runtime_error</a>-throwing methods. Well, it's a to-do; decide later.</dd></dl>
<h2>To-dos and future features </h2>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000019">Todo:</a></b></dt><dd>The comments (as of this writing, all written by me, ygoldfel) in this library could use an edit to make them briefer. (I've found even a self-edit by me, with that express purpose, often does wonders.) Background: I write very extensive comments. I am quite convinced this is superior (far superior even) to next-to-no comments; and to the average amount of comments one tends to see in production code. <em>That said</em>, the top code review feedback I receive (not here specifically but in general) is that my comments tend to be too "discursive" (consisting of discourse) and/or at times unnecessarily in-depth. Discursive = as if I am talking to the reader (many prefer a terser, more formal style). Too in-depth = tends to go into history, related issues, future work, etc. (these elements can remain but can be cut down significant without losing much substance). In other words, there should be a happy middle in terms of comment volume, and this can be achieved by a comment edit run by Yuri or someone else (if reviewed by Yuri). To be clear, I believe this middle ground is to be closer to the status quo than to the average amount of comments in other projects.</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000020">Todo:</a></b></dt><dd>Be more specific (cite date) when writing "as of this writing." I use a rhetorical trick when commenting the state of something that may not continue to be the case. Though I do avoid writing such things, often it is necessary; in that case I usually write "as of this writing" or something very similarly worded. That's fine and essentially the best one can do. It means technically the statement won't become false, even if the "sub-statement" (the thing that was true when written) does become false. However, obviously, to the reader of the comment at that later time, that's little consolation: they're still reading a possibly false statement and will want to know what the situation is THEN, or "as of the reading," to to speak. In order to at least try to be helpful, in those cases a date (numeric month/year &ndash; like 4/2017 &ndash; should be sufficient in most cases) should be supplied. The to-do is to convert all "as of this writing" instances &ndash; and to always add a date when writing new instances of "as of this writing." The to-do can be removed once the conversion is completed. Example: this to-do has not been completed as of this writing (11/2017). (Side note: possibly goes without saying, but one is free to explain to an arbitrary degree of detail why something is true as of that writing, and how/why/when it might change. This to-do covers those cases where no such explanation is written. It would be impractically verbose to get into speculative detail for every as-of-this-writing instance; so at least a date should thus be inserted.)</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000021">Todo:</a></b></dt><dd>There are some boost.thread "interruption points" throughout the code, so we should investigate whether we must catch <code>boost::thread_interrupted</code> in those spots, or what...?</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000022">Todo:</a></b></dt><dd>Inline things: Or just use <code>gcc -O3</code> (and non-<code>gcc</code> equivalents) for prettier/faster-to-compile code? The latter is definitely tempting if it works sufficiently well. So far we've been using <code>gcc -O3</code> and equivalents, and it seems to be working well (turning off inlining results in huge performance losses). Still, I am not sure if it would be better to explicitly <code>inline</code> functions instead. Not having to do so definitely simplifies the code, so it is my great hope that the answer is no, and we can keep using <code>gcc -O3</code> and equivalents. In that case delete this paragraph. (To be clear: <code>gcc -O3</code> means that it ignores <code>inline</code> keyword and anything similar, including inlined method bodies inside <code>class {}</code> and <code>struct {}</code>. Instead it determines what to inline based on its own ideas on what will generate the fastest code (with reasonable code size). <code>gcc -O2</code>, on the other hand, will mostly inline things explicitly declared as such in code (again, via <code>inline</code> or inlining inside class bodies or other techniques).) Update: Now using clang (not gcc) with maximum auto-inlining AND FLTO (link-time optimization will allow inlining across object file boundaries) in at least some platforms. This should be close to as good as possible. Update: gcc auto-inlining+FLTO also works.</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000023">Todo:</a></b></dt><dd>One space after period, not two: For some reason in this project I've been following the convention &ndash; in comments and (I think) log messages &ndash; of two spaces after a sentence-ending punctuator (usually period) before the next sentence's first character. I now regret trying this annoying convention. Go back to one space. (For the record, it does look sort of nice, but that's a matter of opinion, and single space looks fine too... AND doesn't confuse various editors' auto-formatting facilityies, among other problem.)</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000024">Todo:</a></b></dt><dd>We use <code>0</code> instead of <code>NULL</code> or <code>nullptr</code> when needing a null pointer; perhaps we should use the latter. <code>NULL</code> is an anachronism from C, so we shouldn't use it. <code>nullptr</code> is at least no worse than <code>0</code>, however, other than being less concise. However, the main reason it exists &ndash; to avoid ambiguities in function overloading (e.g., when something could take either an <code>int</code> or a <code>char*</code>, <code>nullptr</code> would resolve to the latter, while <code>0</code> probably unintentionally to the former) &ndash; is not a situation our style ever invokes, to my knowledge, so using <code>nullptr</code> would not solve any actual problems. However, it could be argued that using it more readily calls attention to the use of a pointer, as opposed to an integer, in the particular context at play. So it's something to consider (but, no doubt, the conversion process would be laborious, as there's no simple search-replace that would work).</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000025">Todo:</a></b></dt><dd><code>= default</code> for copy constructors and copy operators is now used in a few places; consider spreading this C++11 feature everywhere it's being done implicitly due to C++03 rules (good documentation practices suggest declaring them explicitly but of course leave the implementation to the compiler default, gaining best of both worlds &ndash; proper class API docs yet maintenance-friendly default body).</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000026">Todo:</a></b></dt><dd>Consider PIMPL and related topics. Recommend scouring Boost docs, particularly for the smart pointer library, which discuss how to potentially use smart pointers for easy PIMPLing. In general, research the state of the art on the topic of library interface vs. implementation/hiding.</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000027">Todo:</a></b></dt><dd><code>std::string_view</code> is a way to pass things around similarly to <code>const std::string&amp;</code> without requiring that a <code>string</code> be created just for that purpose; it has a highly similar API but can be constructed from any character sequence in memory and internally stores nothing more than a pointer and length; we should use it wherever possible (within reason) instead of <code>const std::string&amp;</code>. Much code now uses <code>String_view</code>; the remaining to-do is: scour the rest of the code for possible <code>const string&amp;</code>s to convert and indeed convert those to <a class="el" href="namespaceflow_1_1util.html#ae4dc52186797094b3040379ff19124c9" title="Commonly used char-based Basic_string_view. See its doc header.">util::String_view</a>.</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000028">Todo:</a></b></dt><dd>Return-by-copy binary operators of the form <code>T operatorBLAH(const T&amp; x1, const Some_type&amp; x2)</code> should be written as free functions instead of <code>T</code> members. I don't recall at this point why, but this tends to be recommended and done in STL and Boost. Maybe check the Meyer Effective C++ book on the theory; and if it makes sense find all such operators written as members and change them to be free functions. Should this be avoided if it requires <code>friend</code> though? Lastly, for Doxygen, use the <code>relatesalso T</code> command to link the free function to the class <code>T</code> in the documentation.</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000029">Todo:</a></b></dt><dd>In many (most) cases we pass <code>shared_ptr</code>s (and their aliases) by value when it would be more performant to do so by <code>const</code> reference; at times possibly better to pass by raw pointer. Scott Meyer/Herb Sutter have opined on this to basically indicate that (1) it is often best to use a raw pointer, unless actual copying/ownership status is expected; but failing that (2) it is often best to use a <code>const&amp;</code> when safe; and failing that passing by value is fine. This need not be a dogmatic change, but we should be more mindful than simply always passing by value. When searching for instances to potentially change, check for <code>shared_ptr</code>, <code>Ptr</code>, and <code>_ptr</code> tokens. </dd></dl>
</div><h2 class="groupheader">Typedef Documentation</h2>
<a id="a29eaaa9d0fac4ce87d8b969222dbed09" name="a29eaaa9d0fac4ce87d8b969222dbed09"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a29eaaa9d0fac4ce87d8b969222dbed09">&#9670;&nbsp;</a></span>Error_code</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09">flow::Error_code</a> = typedef boost::system::error_code</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Short-hand for a <a class="el" href="namespaceboost_1_1system.html" title="We may add some ADL-based overloads into this namespace outside flow.">boost.system</a> error code (which basically encapsulates an integer/<code>enum</code> error code and a pointer through which to obtain a statically stored message string); this is how Flow modules report errors to the user; and we humbly recommended all C++ code use the same techniques. </p>
<dl class="section note"><dt>Note</dt><dd>It is not inside <a class="el" href="namespaceflow_1_1error.html" title="Flow module that facilitates working with error codes and exceptions; essentially comprised of niceti...">flow::error</a> namespace due to its (<code>Error_code</code>'s) ubiquity. Very few other symbols should follow suit. We may decide to move it there after all.</dd></dl>
<h3>Basic error-emitting API semantics</h3>
<p >All error-reporting Flow APIs follow the following pattern of error reporting semantics. Each API looks something like:</p>
<div class="fragment"><div class="line">return_type Some_class::some_op(..., <a class="code hl_typedef" href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09">flow::Error_code</a>* err_code)</div>
<div class="ttc" id="anamespaceflow_html_a29eaaa9d0fac4ce87d8b969222dbed09"><div class="ttname"><a href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09">flow::Error_code</a></div><div class="ttdeci">boost::system::error_code Error_code</div><div class="ttdoc">Short-hand for a boost.system error code (which basically encapsulates an integer/enum error code and...</div><div class="ttdef"><b>Definition:</b> <a href="common_8hpp_source.html#l00508">common.hpp:508</a></div></div>
</div><!-- fragment --><p >Then, there are two possibilities. If you pass in non-null <code>err_code</code>, then after return <code>*err_code</code> is success (falsy) or a truthy <code>enum</code>-like value, representing a specific error. If, instead, you pass in null, then a <a class="el" href="classflow_1_1error_1_1Runtime__error.html" title="An std::runtime_error (which is an std::exception) that stores an Error_code.">flow::error::Runtime_error()</a> <code>exc</code> is thrown if and only if <code>*err_code</code> would have been set to truthy value <code>e_c</code> had a non-null <code>err_code</code> been passed in. If such an exception is thrown, <code>Error_code e_c</code> is encapsulated in exception object <code>exc</code>. If and only if no exception is thrown, there was no error (<code>*err_code</code> would have been falsy).</p>
<p >Thus, you get the best of both worlds: you can get the simplicity and performance of an error code; or the various features of an exception (including access to the error code via <code>exc.code()</code> if desired), with the same API signature. (boost.asio follows a similar concept, though it requires two API signatures for each operation, one without an <code>Error_code</code> argument, and one with non-<code>const</code> <code>Error_code&amp;</code> out-arg. The above convention is more compact; plus we provide certain tools to reduce boiler-plate in connection with this.)</p>
<h3>Intro to <code>Error_code</code>, a/k/a <a class="el" href="namespaceboost_1_1system.html" title="We may add some ADL-based overloads into this namespace outside flow.">boost.system</a> <code>error_code</code></h3>
<p >(I am restating <a class="el" href="namespaceboost_1_1system.html" title="We may add some ADL-based overloads into this namespace outside flow.">boost.system</a> documentation here, but that particular set of docs is notoriously formal-but-reader-unfriendly.)</p>
<p >A truthy <code>Error_code</code> is a very lightweight &ndash; <code>errno</code>-like in that regard &ndash; value indicating the error that occurred. It stores an <code>int</code> code and a "category" pointer (basically, thing specifying to what code set this belongs). The <code>int</code> is to be converted from the error code set of choice, whereas the category pointer is internally magically determined based on the type of the error code value being converted to <code>Error_code</code>.</p>
<p >An <code>Error_code</code> itself can be serialized into <code>ostream</code>s (and thus <code>string</code>s via <code>lexical_cast</code>, etc.) easily for logging purposes/etc. You can access both the numeric code and a human explanation of the error. Any and all error code sets are supported by this <a class="el" href="namespaceboost_1_1system.html" title="We may add some ADL-based overloads into this namespace outside flow.">boost.system</a> type. POSIX <code>errno</code>s are one possible set of codes; boost.asio has its own code set; and other modules in <code>flow</code> may introduce their own code sets. All are compatible for equality/assignment/etc. with this general <code>Error_code</code> type.</p>
<p >As stated, all error-emitting Flow public APIs (regardless of module) use the above-described error-reporting conventions. In addition, we humbly recommend Flow <em>user</em> code adopt the same battle-tested conventions. However that is absolutely not required and is entirely independent of the fact that Flow modules use them. Do note this convention is battle-tested in boost.asio as well; though Flow's version is more compact; by using a pointer (which can be null) instead of a reference it cuts the number of error-emitting API functions in half.</p>
<p >For each function (including each publicly exported error-reporting function within Flow) that indeed agrees to use the above convention, follow these instructions:</p>
<p >To reduce boiler-plate, within reason, it is incumbent on each error-reporting method to use the following technique:</p>
<ul>
<li>The method signature should be similar to the above (including naming it <code>err_code</code>) and use the above semantics.<ul>
<li>Use <a class="el" href="error_2error_8hpp.html#a636b2d30a8785df6e84646b568bce9b5" title="Narrow-use macro that implements the error code/exception semantics expected of most public-facing Fl...">FLOW_ERROR_EXEC_AND_THROW_ON_ERROR()</a> (and/or nearby similar utilities in flow/error/error.hpp) for minimal boiler-plate that implements these semantics. See doc header for that macro for details.</li>
</ul>
</li>
<li>You may or may not indicate the lack or presence of an error condition via some additional non-exception technique such as a <code>bool</code> return value.</li>
<li><p class="startli">The error behavior documentation should be <em>confined entirely</em> to the documentation of <code>err_code</code> parameter, so that the above semantics need not be repetitively restated a million times. The text of the parameter's doc should usually be as follows (you may copy/paste to start). In this example the function returns codes from the <code><a class="el" href="namespaceflow_1_1net__flow_1_1error.html#a18e13de77b119ea0f2be411490859482" title="All possible errors returned (via flow::Error_code arguments) by flow::net_flow functions/methods.">net_flow::error::Code</a></code> code set <code>enum</code>; but please substitute your code set of choice (again; <code>errno</code> and boost.asio error codes are 2 possible other examples of code sets). Here we go:</p>
<div class="fragment"><div class="line"><span class="comment">// param err_code</span></div>
<div class="line"><span class="comment">//       See flow::Error_code docs for error reporting semantics.  net_flow::error::Code generated:</span></div>
<div class="line"><span class="comment">//       net_flow::error::Code::S_(...) (optional comment), ...more... , net_flow::error::Code::S_(...)</span></div>
<div class="line"><span class="comment">//       (optional comment).</span></div>
</div><!-- fragment --></li>
</ul>
<dl class="section see"><dt>See also</dt><dd>The doc header (and code inside) <code>namespace</code> <a class="el" href="namespaceflow_1_1net__flow_1_1error.html" title="Namespace containing the net_flow module&#39;s extension of boost.system error conventions,...">flow::net_flow::error</a> is a good primer showing how to create an <code><a class="el" href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09" title="Short-hand for a boost.system error code (which basically encapsulates an integer/enum error code and...">Error_code</a></code>-compatible set of <a class="el" href="namespaceflow_1_1error.html" title="Flow module that facilitates working with error codes and exceptions; essentially comprised of niceti...">error</a> codes. This is easier to understand than boost.asio's counterpart for example.</dd></dl>
<dl class="section note"><dt>Note</dt><dd><a class="el" href="namespaceboost_1_1system.html" title="We may add some ADL-based overloads into this namespace outside flow.">boost.system</a> at some point &ndash; I (ygoldfel) am fairly sure after I designed the above ages ago &ndash; introduced an alternate idiom for passing an <a class="el" href="namespaceflow.html#a29eaaa9d0fac4ce87d8b969222dbed09" title="Short-hand for a boost.system error code (which basically encapsulates an integer/enum error code and...">Error_code</a> out-arg that is to be ignored in favor of throwing an exception if omitted. We use the idiom: <code>Error_code*</code> out-arg, throw if null. They, instead propose: <code>Error_code&amp;</code> out-arg, throw if it equals <code>boost::system::throws()</code>. That's great, too, but actually our idiom hews to another bit of the Flow coding style/guide, wherein out-args should be pointers, not non-<code>const</code> references &ndash; and is otherwise very similar. So it's fine. Note that their idiom vs. ours = orthogonal to the main difficulty which is the boiler-plate associated with actually throwing vs. non-throwing; this would be required regardless of the API idiom chosen. The above (involving <a class="el" href="error_2error_8hpp.html#a636b2d30a8785df6e84646b568bce9b5" title="Narrow-use macro that implements the error code/exception semantics expected of most public-facing Fl...">FLOW_ERROR_EXEC_AND_THROW_ON_ERROR()</a>, etc.) is really the main crux of it. </dd></dl>

<p class="definition">Definition at line <a class="el" href="common_8hpp_source.html#l00508">508</a> of file <a class="el" href="common_8hpp_source.html">common.hpp</a>.</p>

</div>
</div>
<a id="a8f2e48761f9ca3ffcaa29872078bbf00" name="a8f2e48761f9ca3ffcaa29872078bbf00"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8f2e48761f9ca3ffcaa29872078bbf00">&#9670;&nbsp;</a></span>Fine_clock</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="namespaceflow.html#a8f2e48761f9ca3ffcaa29872078bbf00">flow::Fine_clock</a> = typedef boost::chrono::high_resolution_clock</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Clock used for delicate time measurements, such that the <code>now()</code> method gets the current time relative to some unknown but constant epoch (reference point). </p>
<p >Used to measure durations of things. It has the following properties:</p>
<ul>
<li>Steady: time cannot go backwards (e.g., via user time change, NTP); time values increment at a rate proportional to real time (no leap seconds for example).</li>
<li>High-resolution: the increments of time at which the clock runs are as small as supported by the OS+hardware. This should be at most a handful of microseconds in practice.</li>
</ul>
<p >So basically it's a precise clock with no surprises (which is more than can be said for stuff people tend to be forced to use, like <code>gettimeofday()</code>). </p>

<p class="definition">Definition at line <a class="el" href="common_8hpp_source.html#l00410">410</a> of file <a class="el" href="common_8hpp_source.html">common.hpp</a>.</p>

</div>
</div>
<a id="a48799f1263cdeedec125be51a3db2b79" name="a48799f1263cdeedec125be51a3db2b79"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a48799f1263cdeedec125be51a3db2b79">&#9670;&nbsp;</a></span>Fine_duration</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="namespaceflow.html#a48799f1263cdeedec125be51a3db2b79">flow::Fine_duration</a> = typedef Fine_clock::duration</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>A high-res time duration as computed from two <code>Fine_time_pt</code>s. </p>

<p class="definition">Definition at line <a class="el" href="common_8hpp_source.html#l00416">416</a> of file <a class="el" href="common_8hpp_source.html">common.hpp</a>.</p>

</div>
</div>
<a id="a9d9cc2eeb10d398cff5591d446b763b8" name="a9d9cc2eeb10d398cff5591d446b763b8"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a9d9cc2eeb10d398cff5591d446b763b8">&#9670;&nbsp;</a></span>Fine_time_pt</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="namespaceflow.html#a9d9cc2eeb10d398cff5591d446b763b8">flow::Fine_time_pt</a> = typedef Fine_clock::time_point</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>A high-res time point as returned by <code>Fine_clock::now()</code> and suitable for precise time math in general. </p>

<p class="definition">Definition at line <a class="el" href="common_8hpp_source.html#l00413">413</a> of file <a class="el" href="common_8hpp_source.html">common.hpp</a>.</p>

</div>
</div>
<a id="a96b8a241b21c907e96cb91f4bf868446" name="a96b8a241b21c907e96cb91f4bf868446"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a96b8a241b21c907e96cb91f4bf868446">&#9670;&nbsp;</a></span>int8_t</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="namespaceflow.html#a96b8a241b21c907e96cb91f4bf868446">flow::int8_t</a> = typedef signed char</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Signed byte. Prefer to use <code>uint8_t</code> when representing binary data. This is 8 bits on all modern systems. </p>

<p class="definition">Definition at line <a class="el" href="common_8hpp_source.html#l00393">393</a> of file <a class="el" href="common_8hpp_source.html">common.hpp</a>.</p>

</div>
</div>
<a id="ae02da22c4a101eaab447511c905e4f32" name="ae02da22c4a101eaab447511c905e4f32"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae02da22c4a101eaab447511c905e4f32">&#9670;&nbsp;</a></span>uint8_t</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">using <a class="el" href="namespaceflow.html#ae02da22c4a101eaab447511c905e4f32">flow::uint8_t</a> = typedef unsigned char</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Byte. Best way to represent a byte of binary data. This is 8 bits on all modern systems. </p>

<p class="definition">Definition at line <a class="el" href="common_8hpp_source.html#l00391">391</a> of file <a class="el" href="common_8hpp_source.html">common.hpp</a>.</p>

</div>
</div>
<h2 class="groupheader">Enumeration Type Documentation</h2>
<a id="a3938730ab4b89daf13d027a5f620e7ce" name="a3938730ab4b89daf13d027a5f620e7ce"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a3938730ab4b89daf13d027a5f620e7ce">&#9670;&nbsp;</a></span>Flow_log_component</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">enum class <a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce">flow::Flow_log_component</a></td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">strong</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>The <a class="el" href="classflow_1_1log_1_1Component.html" title="A light-weight class, each object storing a component payload encoding an enum value from enum type o...">flow::log::Component</a> payload enumeration comprising various log components used by Flow's own internal logging. </p>
<p >Internal Flow code specifies members thereof when indicating the log component for each particular piece of logging code. Flow user specifies it, albeit very rarely, when configuring their program's logging such as via <a class="el" href="classflow_1_1log_1_1Config.html#a9b7ba819538d221f190e044cfa6220db" title="Registers a generically-typed enum class that represents the full set of the calling module&#39;s possibl...">flow::log::Config::init_component_to_union_idx_mapping()</a> and <a class="el" href="classflow_1_1log_1_1Config.html#a146a60d96256dbaed4f5f0e7dcd8f529" title="Registers the string names of each member of the enum class Component_payload earlier registered via ...">flow::log::Config::init_component_names()</a>.</p>
<p >If you are reading this in Doxygen-generated output (likely a web page), be aware that the individual <code>enum</code> values are not documented right here, because <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> auto-generates those via certain macro magic, and Doxygen cannot understand what is happening. However, you will find the same information directly in the source file <code><a class="el" href="log__component__enum__declare_8macros_8hpp.html">log_component_enum_declare.macros.hpp</a></code> (if the latter is clickable, click to see the source).</p>
<h3>Details regarding overall log system init in user program</h3>
<p >The following is a less formal reiteration of <a class="el" href="classflow_1_1log_1_1Config.html" title="Class used to configure the filtering and logging behavior of Loggers; its use in your custom Loggers...">flow::log::Config</a> documentation and is presented here &ndash; even though technically in the present context Flow itself is nothing more than yet another module that uses <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> for its own logging &ndash; for your convenience. Flow's own logging can be seen as the canonical/model use of <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a>, so other <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> users can read this to learn the basics of how to configure loggingg. That's why we re-explain this info here, in brief form:</p>
<p >Your program &ndash; that uses the present library &ndash; can register this <code>enum</code> in order for these components (and particularly the log messages that specify them via <a class="el" href="classflow_1_1log_1_1Log__context.html" title="Convenience class that simply stores a Logger and/or Component passed into a constructor; and returns...">flow::log::Log_context</a> or <a class="el" href="log_8hpp.html#ae4b5d4fdd2eb052615620879dd74af95" title="For the rest of the block within which this macro is instantiated, causes all FLOW_LOG_....">FLOW_LOG_SET_CONTEXT()</a>) to be logged properly in that program, co-existing correctly with other code bases that use <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> for logging. Typically one constructs a <code><a class="el" href="classflow_1_1log_1_1Config.html" title="Class used to configure the filtering and logging behavior of Loggers; its use in your custom Loggers...">flow::log::Config</a> C</code> and then at some point before logging begins:</p><ul>
<li>For each <code>enum class X_log_component</code> (note that <code>Flow_log_component</code> is only one such <code>enum class</code>):<ol type="1">
<li><code>C.init_component_to_union_idx_mapping&lt;X_log_component&gt;(K)</code>, where <code>K</code> is a distinct numeric offset, maybe multiple of 1000.</li>
<li><code>C.init_component_names&lt;X_log_component&gt;(S_X_LOG_COMPONENT_NAME_MAP, ..., "X-")</code>.<ul>
<li>Note the "X-" prefix, allowing one to prepend a namespace-like string prefix to avoid any output and config clashing.</li>
</ul>
</li>
<li><code>C.configure_default_verbosity(Sev::S)</code>, where <code>S</code> is some default max severity.</li>
<li>For each component <code>M</code> for which one desires a different max severity <code>S</code>:<ul>
<li><code>C.configure_component_verbosity&lt;X_log_component&gt;(Sev::S, X_log_component::M)</code>. OR:</li>
<li><code>C.configure_component_verbosity_by_name(Sev::S, "X-M")</code>.</li>
</ul>
</li>
</ol>
</li>
<li>Apply <code>C</code> to the <a class="el" href="classflow_1_1log_1_1Logger.html" title="Interface that the user should implement, passing the implementing Logger into logging classes (Flow&#39;...">flow::log::Logger</a> or <code>Logger</code>s you want to affect.</li>
<li>Pass the <code>Logger</code> or <code>Logger</code>s to appropriate APIs that want to log.</li>
</ul>
<p >One could make changes after logging has begun, but that's a separate topic. </p>
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="a3938730ab4b89daf13d027a5f620e7cea6fba12db09e5bebfaa04f6372c41c2cf" name="a3938730ab4b89daf13d027a5f620e7cea6fba12db09e5bebfaa04f6372c41c2cf"></a>S_END_SENTINEL&#160;</td><td class="fielddoc"><p >CAUTION &ndash; see <a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce" title="The flow::log::Component payload enumeration comprising various log components used by Flow&#39;s own int...">flow::Flow_log_component</a> doc header for directions to find actual members of this <code>enum class</code>. </p>
<p >This entry is a placeholder for Doxygen purposes only, because of the macro magic involved in generating the actual <code>enum class</code>. </p>
</td></tr>
</table>

<p class="definition">Definition at line <a class="el" href="common_8hpp_source.html#l00637">637</a> of file <a class="el" href="common_8hpp_source.html">common.hpp</a>.</p>

</div>
</div>
<h2 class="groupheader">Variable Documentation</h2>
<a id="abef6a1249edc3dd6c7f650235a84bfe4" name="abef6a1249edc3dd6c7f650235a84bfe4"></a>
<h2 class="memtitle"><span class="permalink"><a href="#abef6a1249edc3dd6c7f650235a84bfe4">&#9670;&nbsp;</a></span>S_FLOW_LOG_COMPONENT_NAME_MAP</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">const boost::unordered_multimap&lt;<a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce">Flow_log_component</a>, std::string&gt; flow::S_FLOW_LOG_COMPONENT_NAME_MAP</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">extern</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>The map generated by <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> macro magic that maps each enumerated value in <a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce" title="The flow::log::Component payload enumeration comprising various log components used by Flow&#39;s own int...">flow::Flow_log_component</a> to its string representation as used in log output and verbosity config. </p>
<p >Flow user specifies, albeit very rarely, when configuring their program's logging via <a class="el" href="classflow_1_1log_1_1Config.html#a146a60d96256dbaed4f5f0e7dcd8f529" title="Registers the string names of each member of the enum class Component_payload earlier registered via ...">flow::log::Config::init_component_names()</a>.</p>
<p >As a Flow user, you can informally assume that if the component <code>enum</code> member is called <code>S_SOME_NAME</code>, then its string counterpart in this map will be auto-computed to be <code>"SOME_NAME"</code> (optionally prepended with a prefix as supplied to <a class="el" href="classflow_1_1log_1_1Config.html#a146a60d96256dbaed4f5f0e7dcd8f529" title="Registers the string names of each member of the enum class Component_payload earlier registered via ...">flow::log::Config::init_component_names()</a>). This is achieved via <a class="el" href="namespaceflow_1_1log.html" title="Flow module providing logging functionality.">flow::log</a> macro magic.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="namespaceflow.html#a3938730ab4b89daf13d027a5f620e7ce" title="The flow::log::Component payload enumeration comprising various log components used by Flow&#39;s own int...">flow::Flow_log_component</a> first. </dd></dl>

</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Mar 28 2025 22:55:35 for Flow by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
